Locating Rule Extension

A trackable can be associated with several location providers. For example, a trackable may have a GPS provider used for outdoor localization, as well as UWB and RFID location providers for indoor localization.

In practice this may result in multiple location updates at a time for each of the location providers. For example, the trackable may be located indoors and get a precise location via UWB while it gets a GPS location update with low accuracy at the same time. As a result, the trackable will get all location updates for each of its devices, and by default the most recent location update is marked as the most significant.

The trackable locating rule extension adds additional configuration options to a trackable in order to make fine-grained decisions about selecting the most significant location. Locating rules can be expressed via a simple domain specific language.

For a comprehensive overview of this extension, refer to our video on YouTube.

Details

Each rule consists of two properties:

• expression: A boolean expression consisting of AND connected expressions. The syntax is based on SQL.
• priority: The priority assigned to the associated expression. It is a positive number, with 0 being the lowest priority.

A list of such rules can be assigned to a trackable or as default rules. The default rules are used for all trackables, which do not contain rules. If neither rules are present, the most recent location update has the highest priority. The default rules can be set with this API endpoint:
/trackables/rules/locating

Whenever a location update is processed all rules are evaluated for all locations associated with a trackable. Based on all expressions which evaluate to true, the largest priority is assigned to the respective location. The location with the highest priority is then assigned to the trackable as the most significant location. If no expression evaluates to true, a default priority of 0 is used.

A dedicated API for testing the expression syntax can be found at:
/validator/rules/locating

Available Functions and Properties

timestamp_diff

This function provides access to the "age" of a location update. It gives the time difference between the location's timestamp_generated and now in milliseconds.

accuracy

This enables checks against the accuracy of the location update in metres.

provider_id

This enables checks against the location provider id of the location update.

type

This enables checks against the location provider type of the location update. Available types are: uwb, gps, wifi, rfid, ibeacon, virtual, unknown

source

This enables checks against the source/zone of the location update.

floor

This enables checks against the floor of the location update.

speed

This enables checks against the speed of the location update in metres per second.

Available Operators

The most relevant operators understood by the DeepHub are listed below. Expressions built from these operators can be grouped with parentheses: ( and ).

Operator	Description
* / % + -	Arithmetic operators: Multiply, divide, modulo, add, subtract
& | << >>	Bitwise operators: Binary AND, binary OR, binary left shift, binary right shift
< > <= >= = !=	Comparison operators: Less than, greater than, less than or equal, greater than or equal, equals, is not equal
ISNULL NOTNULL	Null comparison operators: check if a value equals or doesn't equal null
NOT AND OR	Logical operators: negate operator, AND operator, OR operator
LIKE	Check if a string matches a given pattern. The '%' wildcard matches any sequence of zero or more characters following the wildcard. The '_' wildcard matches a single character.

Example

The following locating rules would be described in natural language as:

• Use the precise UWB location if the location is not older than 10 seconds,
• Otherwise switch back to GPS if the accuracy is better than 10 metres.

"locating_rules": [
  {
    "expression": "type = 'uwb' AND timestamp_diff < 10000",
    "priority": 10
  },
  {
    "expression": "type = 'gps' AND accuracy < 10",
    "priority": 9
  }
]